Updating the Integrator platform

Administrators can use JMS messages to dynamically update the configuration of a running Integrator platform. Configuration Update request messages for the general Integrator configuration (XPDinteg.xml) or the User Admin store configuration (XPDintegRoles.xml) can be sent to the Integrator platform. These message must use the custom JMS header provided by Integrator. These request messages are application control messages and must be sent to the Expeditor integrator CtrlQ.

The ConfigUpdate message should be used to update the general Integrator configuration or the User Admin store configuration.

Table 1: ConfigUpdate message definition

MessagePurpose	TransportType	ResourceType	Required custom header properties and values / Comment
ConfigUpdate	-	ConfigUpdateFile	-ResourceCmd={FILE | ParamList};[Command:{restart | stop};Param:console,reset] -DestinationPath & -Name -DestinationCreationMode (APPEND | OVERWRITE) -MessageId, TransactionId, LocationId, MessageSrcId
ConfigUpdate	-	UserConfigUpdateFile	-ResourceCmd={UserConfigFILE | UserConfigParamList};[Command:{restart | stop};Param:console,reset] -DestinationPath & -Name -DestinationCreationMode (APPEND | OVERWRITE) -TransferConfirmationMode: NONE | DELETE | WriteOther -MessageId, TransactionId, LocationId, MessageSrcId

• The ResourceCmd specifies the possible update modes:
• Either a complete configuration file is transferred. Then the DestinationPath/-Name are also required.
• or a list of parameters is sent in the message payload.
• The DestinationPath and -Name properties contain the target path and name of the local file system to which the configuration file in the message payload is detached and from where the changes are applied (default would be /config/new/XPDinteg.xml or /config/XPDintegRoles.xml).
• The TransferConfirmationMode property can only be used for updating the User Admin configuration:
• NONE - received update file is stored in under the default location /config. Important: The name of the transferred file is maintained!
• DELETE – only the User Admin store configuration is updated, no local copy of XPDintegRoles.xml is is kept (recommended behaviour).
• WriteOther - received update file is stored under the name and location specified under updatesFileLocation
• MessageId, TransactionId, LocationId and MessageSrcId must be provided so that the log message can be created appropriately.
• The Command specifies whether to restart or stop the Expeditor integrator runtime. The Param options further define whether:console – runtime runs in an open OSGi Console (recommended)
• reset –Expeditor integrator should be re-set before restarting (Careful: re-creates all local messaging components and deletes existing messages in queues!)

There are four options for sending a configuration update to the remote Expeditor integrator runtime:

1. Sending a complete configuration file in the message payload (XPDinteg.xml):
• MessagePurpose=ConfigUpdate
• ResourceCmd=FILE;[Command:{restart | stop};Param:console,reset]
2. Sending a list of changed properties in the message only (for XPDinteg.xml).
• MessagePurpose=ConfigUpdate
• ResourceCmd=ParamList;[Command:{restart | stop};Param:console,reset]
  
  The message payload contains a list of selected properties of the XPDintegConfig.xml file. These properties are used to set the specific attributes of the integrator bundles using this flow. For example, the message body changing the Custom Log Service into Maintenance Mode would look like this:
  
  Listing 20: ConfigUpdate message payload for updating the Maintenance Mode property
  
  

    <?xml version="1.0" encoding="utf-8"?>
  
  <configurations>
  
      <configuration pid="com.ibm.rcp.integrator.customeventservice">
  
  <properties>
  
  	    <property name="MaintenanceMode" value="ON"/>
  
  </properties>
  
      </configuration>
  
  </configurations>  

3. Sending a complete User Admin store configuration file in the message payload (XPDintegRoles.xml):
• MessagePurpose=ConfigUpdate
• ResourceCmd=UserConfigFILE;[Command:{restart | stop};Param:console,reset]
4. Sending a list of changed User Admin store configuration properties in the message only (for XPDintegRoles.xml).
• MessagePurpose=ConfigUpdate
• ResourceCmd=UserConfigParamList;[Command:{restart | stop};Param:console,reset]

The message payload contains a list of selected properties of the XPDintegRoles.xml file.

For ResourceCmd=FILE;[Command:{restart | stop};Param:console,reset] the Default_ConfigUpdate.flow is triggered. This flow contains the following Activities which are sequentially executed:

• MessageReadActivity – Reads the Message from the CtrlQ.
• MessageToFileActivity – Converts the input message to a File. In memory representation of XPDinteg.xml file.
• FileWriteToFileSystemActivity – Writes the in memory representation of XPDinteg.xml file into /config directory.
• TransformAndValidateActivity – Verfies the XPDinteg.xml file structure and transforms it into the XPDintegConfig.xml file and stores it the in memory.
• FileWriteToFileSystemActivity – Writes the in memory XPDintegConfig.xml file into /config/system folder.
• ConfigStoreUpdateActivity – Transactional update of the OSGi configuration with the XPDintegConfig.xml file contents.
• PlatformRestartActivity – Restarts the platform based on the ResoruceCmd Attributes.

For ResourceCmd=ParamList;[Command:{restart | stop};Param:console,reset] the Default_ConfigUpdateResourceCmd.flow is triggered. This flow contains the following Activities which are sequentially executed:

• MessageReadActivity – Reads the Message from the CtrlQ.
• RertriveAndUpdateConfigurationStoreActivity- Gets the configuration store using OSGi Configuration Admin and updates the information contained in the message payload. Creates an in memory representation XPDinegConfig.xml file.
• FileWriteToFileSystemActivity – Writes the in memory representation of XPDintegConfig.xml file into /config/system directory.
• ConfigStoreUpdateActivity – Transactional update of the OSGi configuration with the XPDintegConfig.xml file contents.
• PlatformRestartActivity – Restarts the platform based on the ResoruceCmd Attributes.

Running in Maintenance Mode

Administrators can use JMS control messages to turn the Integrator maintenance mode ON or OFF. A Maintenance toggle request message can be sent to the Expeditor integrator which uses the provided JMS custom headers. This message is an application control message and must be sent to the Expeditor integrator CtrlQ.

Note: In Maintenance Mode, neither logging information nor events may be forwarded to the back-end (no monitoring information is created)!
It is configurable which information is still captured and may be even locally persisted (see details in Installing and Configuring the IBM Lotus Expeditor integrator platform).

Table 2: Maintenance mode message definition

MessagePurpose	TransportType	ResourceType	Required custom header properties and values / Comment
Maintenance	-	-	-ResourceCmd={ON | OFF}; [Command:{restart | stop};Param:console,reset] -MessageId, TransactionId, LocationId, MessageSrcId

• The ResourceCmd specifies the executed operation:
  ResourceCmd={ON | OFF}; [Command:{restart | stop};Param:console,reset]
  If the ResourceCmd contains ON then all the bundles maintenance mode property is changed to and if the ResourceCmd contains OFF, then it is changed to .
  
  The Command specifies whether to restart or stop the Expeditor integrator runtime. The Param options further define whether:
  
  console – runtime runs in an open OSGi Console (recommended)
  
  reset –Expeditor integrator should be re-set before restarting (Careful: re-creates all local messaging components and deletes existing messages in queues!)
• MessageId, TransactionId, LocationId and MessageSrcId must be provided so that the log message can be created appropriately.

The JMS Adapter (Resource Adapter) recognizes a new message in the CtrlQ and fires the corresponding event with this topic:
com/ibm/integrator/flowtriggerevent/Maintenance/MESSAGE/JmsAdapter

This event is received by the Application Control Service which kicks off the configured default Maintenance flow (in /flowdefs/system):
Flow file name: Default_MaintenanceModeUpdate.flow

The flow description of the Maintenance Mode is given below. It contains the following Application Control Service Activities which are executed sequentially:

• MessageReadActivity – Reads the Maintenance message from the CtrlQ
• RetrieveAndUpdateConfigurationStoreActivity – Gets the all the latest configuration of all the bundles from the Configuration Store, applies the latest setting to all the bundles and generates the new XML File (XPDintegConfig.xml) with latest changes
• FileWriteToFileSystemActivity – Writes the above generated file to config/system folder
• ConfigStoreUpdateActivity – Updates the OSGi Config Admin Service’s Configuration Store with the latest XML File in a transactional manner.
• PlatformRestartActivity – If the platform commands are given in the ResourceCmd attribute then this will restart the platform using the XPDintegSvc feature

This topic is covered in further detail in the Installing and Configuring the IBM Lotus Expeditor integrator platform (see ‎Ref_1).

Perform Housekeeping

Administrators can configuration the housekeeping process to run automatically within a configurable time interval. Administrators can also configure the resources which are participate in this housekeeping process. Threshold values can be defined and actions which are performed when these thresholds are exceeded

In addition to the automatic house keeping, a housekeeping request message can be sent to the Integrator platform which uses the provided JMS custom headers. This message is an application control message and must be sent to the Expeditor integrator CtrlQ.

Table 3: HouseKeeping message definition

MessagePurpose	TransportType	ResourceType	Required custom header properties and values / Comment
HouseKeeping	-	-	-MessageId, TransactionId, LocationId, MessageSrcId

MessageId, TransactionId, LocationId and MessageSrcId must be provided so that the log message can be created appropriately.

The JMS Adapter (Resource Adapter) recognizes a new message in the CtrlQ and fires the corresponding event with this topic:
com/ibm/integrator/flowtriggerevent/Housekeeping

This event is received by the Application Control Service which kicks off the configured default house keeping flow (in /flowdefs/system):

Flow file name: Default_HouseKeeping.flow

The triggered default flow will contain

• HOUSE_KEEPING_LOCAL_FILE_SYSTEM_ACTIVITY – performs configured house keeping actions on given local files
• HOUSE_KEEPING_JMS_ACTIVITY – performs configured house keeping actions on given local queues
• HOUSE_KEEPING_SYSTEM_RESOURCES_ACTIVITY – performs configured house keeping actions on given system resources (monitoring actions)
• XPDINTEG_FILE_WRITE_TO_FILE_SYSTEM – writes the house keeping report into the /persistent/housekeeping_.log file.
• XPDINTEG_FILE_TO_MESSAGE_WRITE – sends the house keeping report log file to the back-end ResInQ.
• XPDINTEG_FILE_COPY_USING_REFERENCE - backs up the old configuration file with a timestamp in its name.

Note: The STORE_XPD_FILE_WRITE_TO_FILE_SYSTEM and STORE_XPD_FILE_TO_MESSAGE_WRITE activities can have different combinations:

• If both exist, the file is both written to the localfilesystem as /persistent/housekeeping_.log and also sent to the backend ResInQ
• If only STORE_XPD_FILE_WRITE_TO_FILE_SYSTEM exists, the file is only written to the local file system as /persistent/housekeeping_.log
• If only STORE_XPD_FILE_TO_MESSAGE_WRITE exists, the file data is only sent to the backend.

This topic is covered in further detail in Installing and Configuring the IBM Lotus Expeditor integrator platform.

Using ISA for problem determination

(ISA) is a software feature that collects appropriate platform and configuration information for the IBM Support. In case of problems, customers can run the ISA which creates a ZIP file with collected information. Customers can send this back to IBM Support for further investigation of the problem.

Administrators can run the IBM Support Assistant by sending a ISA Collector request message Integrator platform. This message should use the provided custom JMS headers. This message is an application control message and must be sent to the Expeditor integrator CtrlQ in order to start the Problem Determination Flow.

Table 4: ISACollector message definition

MessagePurpose	TransportType	ResourceType	Required custom header properties and values / Comment
ISACollector	-	-	-MessageId, TransactionId, LocationId, MessageSrcId

MessageId, TransactionId, LocationId and MessageSrcId must be provided so that the log message can be created appropriately.

The JMS Adapter (Resource Adapter) recognizes a new message in the CtrlQ and fires the corresponding event with this topic:
com/ibm/integrator/flowtriggerevent/ISACollector/MESSAGE/JmsAdapter

This event is received by the Application Control Service which kicks off the configured default house keeping flow (in /flowdefs/system):

Flow file name: Default_ProblemDetermination.flow

The triggered default flow will contain

• XPDINTEG_MESSAGE_READ - reads the message and passes it on as output.
• ISA_COLLECTOR_ACTIVITY - invokes the ISA Collector which leads to the generation of a ISA Collector ZIP file in a given folder. The output is the path to the created ZIP file.
• XPDINTEG_ISA_COLLECTOR_ADDFILES_ACTIVITY - gets the ZIP file (from input), adds additional files and generates the FileResourceData out of it.

Reliable Data Exchange through Messaging

The Expeditor integrator uses the Lotus Expeditor micro broker and the micro broker bridge for reliable data exchange through messaging. This ensures that the back-end messaging system and the local data exchange at the location of the Expeditor integrator, e.g. in a retail store, are decoupled. Messages are delivered once and only once and as soon as network connectivity is available. Local and remote processes pass data on to the messaging system and continue processing, because locally submitted messages are considered as transferred.

The connectivity from the Expeditor integrator runtime to the local resources, e.g. in the retail example: connectivity of the Store Server to the 4690 PoS System (FTP Server), as well as to the back-end Message Broker is reliably maintained. The following situations are handled automatically:

• Local resource is not available during Expeditor integrator start-up (e.g. FTP Server/4690 Controller):
  All Resource Adapters start up and keep on trying to connect to the monitored resource. As soon as the monitored queue manager, file system, FTP/SSH server, database etc. is available, it will be monitored as configured.
• Back-end messaging system is not available during Expeditor integrator start-up:
  When the back-end Message Broker is not available during application start-up, the Resource Adapters (e.g. FTP, LocalFileSystem) will still monitor the configured files, convert them into messages and send them to the local Expeditor micro broker queues which are bridged to back-end queues. Whenever, the Message Broker back-end becomes available, these locally stored messages are passed on to the back-end by the micro broker bridge, without requiring a restart of the application.
  
  Messages that were received from the back-end will still be processed locally (according to the configured number of RetryAttempts and the set RetryInterval). If the target resource becomes not available within the configured tolerance intervals, the transaction will fail and appropriate status and log messages will be created. In this case, it is configurable whether the message(s) that could not be processed are discarded, put in the Deadletter queue or re-inserted into the inbound queue.

• Local resource attached to the Expeditor runtime environment is not available during Expeditor integrator up time (e.g. FTP Server/4690 Controller):
  All Resource Adapters continue working and keep on trying to re-connect to the monitored resource. As soon as the monitored resource (queue, file system, FTP/SSH server, database resource) becomes available again, it will be monitored as configured.
• Back-end messaging system is not available during Expeditor integrator up time:
  If the connection to the back-end messaging system is temporarily not available, the Expeditor integrator Resource Adapters will continue monitoring the configured resources (e.g. files), convert them into messages and send them to the local micro broker queues that are bridged to back-end queues. Whenever, the back-end Message Broker becomes available again, these locally stored messages are passed on to the back-end by the micro broker bridge, without requiring a restart of the application.